DECLARE Statement (Non-BASIC Procedures) ---------------------------------------------------------------------------- Action Declares calling sequences for external procedures written in other languages. Syntax DECLARE FUNCTION name -CDECL- -ALIAS "aliasname"- -(-parameterlist-)- DECLARE SUB name -CDECL- -ALIAS "aliasname"- -(-parameterlist-)- Remarks The following list describes the parts of the DECLARE statement. ----------------------------------------------------------------------------- Part Description ---------------------------------------------------------------------------- FUNCTION Indicates that the external procedure returns a value and can be used in an expression. SUB Indicates that the external procedure is invoked in the same way as a BASIC SUB procedure. name The name used in the BASIC program to invoke the procedure. Names can Part Description ---------------------------------------------------------------------------- to invoke the procedure. Names can have up to 40 characters. FUNCTION procedure names can include an explicit type character ( %, &, !, #, @, or $) indicating the type of value the procedure returns. CDECL Indicates that the procedure uses the C-language argument order and naming conventions. CDECL passes the arguments from right to left, rather than using the BASIC convention of left to right., CDECL also affects the name used in searches of object files and libraries. If there is no ALIAS clause in the DECLARE statement, Part Description ---------------------------------------------------------------------------- clause in the DECLARE statement, the type-declaration character is removed from the name of the procedure, and an underscore is added to the beginning. This becomes the name used when searching libraries and external files. If CDECL is used with ALIAS, aliasname is used as is. ALIAS Indicates that the procedure being called has another name in the .OBJ or library file.. aliasname The name the procedure has in the file or library. parameterlist The parameters to be passed to the invoked procedure. Part Description ---------------------------------------------------------------------------- invoked procedure. The argument parameterlist has the following syntax. -{BYVAL|SEG}- variable -AS type- -, -{BYVAL|SEG}- variable -AS type--... The following list describes the parts of parameterlist. ----------------------------------------------------------------------------- Part Description ---------------------------------------------------------------------------- BYVAL Indicates the parameter is passed by value, not reference. Reference is the default. BYVAL can be used only with INTEGER, LONG, SINGLE, DOUBLE, and CURRENCY types. Part Description ---------------------------------------------------------------------------- DOUBLE, and CURRENCY types. When BYVAL appears in front of a parameter, the actual argument is converted to the type indicated in the DECLARE statement before being passed. SEG Indicates the parameter is passed as a segmented address (far address). variable A valid BASIC variable name. Only the variable's type is significant. If the variable is an array, it can be followed by the number of dimensions in parentheses (to maintain compatibility with older versions of BASIC). For example. Part Description ---------------------------------------------------------------------------- versions of BASIC). For example. DECLARE SUB EigenValue (A(2) AS DOUBLE) AS type Indicates the variable's type. The argument type can be INTEGER, LONG, SINGLE, DOUBLE, STRING, CURRENCY, ANY, or a user-defined type. You also can indicate the variable's type by including an explicit type character ( %, &, !, #, @, or $) in the variable name or by relying on the default type. When declaring external procedures written in other languages, you can use the ANY keyword in the Part Description ---------------------------------------------------------------------------- can use the ANY keyword in the AS clause. ANY overrides type checking for that argument. You cannot use ANY with arguments passed by value. When neither BYVAL nor SEG is used, arguments are passed as near addresses (offsets). This form of the DECLARE statement lets you refer to procedures written in other languages. The DECLARE statement also causes the compiler to check the number and type of arguments used to invoke the procedure. A DECLARE statement can appear only in module-level code and affects the entire source file. The form of the parameter list determines whether or not argument type checking is done, as described in the following declarations. ----------------------------------------------------------------------------- Declaration Meaning ---------------------------------------------------------------------------- DECLARE SUB First CDECL No argument checking is done when there is no parameter list. DECLARE SUB First CDECL () First has no parameters. If you use arguments in a call to First, BASIC generates an error. Empty parentheses indicate that the SUB or FUNCTION procedure has no parameters and that argument checking should be done. DECLARE SUB First CDECL (X AS LONG) First takes one long-integer argument. When a parameter list appears, the number and type of arguments are checked each invocation. Declaration Meaning ---------------------------------------------------------------------------- invocation. A procedure in a DECLARE statement can be invoked without the CALL keyword. Note You cannot have fixed-length strings in DECLARE statements because only variable-length strings can be passed to SUB and FUNCTION procedures. Fixed-length strings can appear in an argument list but are converted to variable-length strings before being passed. Be careful when using the SEG keyword to pass arrays, because BASIC may move variables in memory before the called routine begins execution. Anything in a CALL statement's argument list that causes memory movement may create problems. You can safely pass variables using SEG if the CALL statement's argument list contains only simple variables, arithmetic expressions, or arrays indexed without the use of intrinsic or user-defined functions. See Also CALL, CALLS Statements (Non-BASIC); DECLARE (BASIC) Example The following example shows a BASIC program that calls a short C function. The C program is compiled separately and stored in a Quick library or explicitly linked to form the .EXE file. DEFINT A-Z DECLARE FUNCTION addone CDECL (BYVAL n AS INTEGER) INPUT x y = addone(x) PRINT "x and y are "; x; y END The following function uses C argument passing and takes a single integer argument passed by value. -* C function addone. Returns one more than its integer argument. *- int far addone(int n) { return(n+1); }